This crate provides the [`Repository`] abstraction which serves as a hub into all the functionality of git.
It's powerful and won't sacrifice performance while still increasing convenience compared to using the sub-crates
individually. Sometimes it may hide complexity under the assumption that the performance difference doesn't matter
for all but the fewest tools out there, which would be using the underlying crates directly or file an issue.
### The Trust Model
It is very simple - based on the ownership of the repository compared to the user of the current process [Trust](sec::Trust)
is assigned. This can be [overridden](open::Options::with()) as well. Further, git configuration files track their trust level
per section based on and sensitive values like paths to executables or certain values will be skipped if they are from a source
that isn't [fully](sec::Trust::Full) trusted.
That way, data can safely be obtained without risking to execute untrusted executables.
Note that it's possible to let `gix` act like `git` or `git2` by setting the [open::Options::bail_if_untrusted()] option.
### The prelude and extensions
With `use git_repository::prelude::*` you should be ready to go as it pulls in various extension traits to make functionality
available on objects that may use it.
The method signatures are still complex and may require various arguments for configuration and cache control.
Most extensions to existing objects provide an `obj_with_extension.attach(&repo).an_easier_version_of_a_method()` for simpler
call signatures.
### `ThreadSafe` Mode
By default, the [`Repository`] isn't `Sync` and thus can't be used in certain contexts which require the `Sync` trait.
To help with this, convert it with [`.into_sync()`][Repository::into_sync()] into a [`ThreadSafeRepository`].
### Object-Access Performance
Accessing objects quickly is the bread-and-butter of working with git, right after accessing references. Hence it's vital
to understand which cache levels exist and how to leverage them.
When accessing an object, the first cache that's queried is a memory-capped LRU object cache, mapping their id to data and kind.
It has to be specifically enabled a [`Repository`].
On miss, the object is looked up and if a pack is hit, there is a small fixed-size cache for delta-base objects.
In scenarios where the same objects are accessed multiple times, the object cache can be useful and is to be configured specifically
using the [`object_cache_size(…)`][crate::Repository::object_cache_size()] method.
Use the `cache-efficiency-debug` cargo feature to learn how efficient the cache actually is - it's easy to end up with lowered
performance if the cache is not hit in 50% of the time.
### Terminology
#### `WorkingTree` and `WorkTree`
When reading the documentation of the canonical gix-worktree program one gets the impression work tree and working tree are used
interchangeably. We use the term _work tree_ only and try to do so consistently as its shorter and assumed to be the same.
### Plumbing Crates
To make using _sub-crates_ and their types easier, these are re-exported into the root of this crate. Here we list how to access nested plumbing
crates which are otherwise harder to discover:
**`git_repository::`**
* [`odb`]
* [`pack`][odb::pack]
* [`protocol`]
* [`transport`][protocol::transport]
* [`packetline`][protocol::transport::packetline]
### `libgit2` API to `gix`
This doc-aliases are used to help finding methods under a possibly changed name. Just search in the docs.
Entering `git2` into the search field will also surface all methods with such annotations.
What follows is a list of methods you might be missing, along with workarounds if available.
* [`git2::Repository::open_bare()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.open_bare) ➡ ❌ - use [`open()`] and discard if it is not bare.
* [`git2::build::CheckoutBuilder::disable_filters()`](https://docs.rs/git2/*/git2/build/struct.CheckoutBuilder.html#method.disable_filters) ➡ ❌ *(filters are always applied during checkouts)*
* [`git2::Repository::submodule_status()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.submodule_status) ➡ [`Submodule::state()`] - status provides more information and conveniences though, and an actual worktree status isn't performed.
#### Integrity checks
`git2` by default performs integrity checks via [`strict_hash_verification()`](https://docs.rs/git2/latest/git2/opts/fn.strict_hash_verification.html) and
[`strict_object_creation`](https://docs.rs/git2/latest/git2/opts/fn.strict_object_creation.html) which `gitoxide` *currently* **does not have**.
### Feature Flags